Inside Macintosh: QuickDraw GX Objects /

Chapter 2 - Shape Objects / Shape Objects Reference

Functions / Creating and Manipulating Shape Objects

GXCopyDeepToShape

The GXCopyDeepToShape function copies the contents of one existing shape to another, or creates a new shape and copies the contents of an existing shape to it. For bitmap shapes, picture shapes, glyph shapes, and layout shapes, GXCopyDeepToShape copies more information than the GXCopyToShape function does.

gxShape GXCopyDeepToShape(gxShape target, gxShape source);

target

A reference to the shape to copy the source shape's contents to. If you specify nil for this parameter, this function creates a new shape.

source

A reference to the shape to copy from.

function result

A reference to the copy (that is, the target shape).

DESCRIPTION

The GXCopyDeepToShape function copies the properties and the geometry of the shape specified by the source parameter into the shape specified by the target parameter. It also copies the references to the source shape's ink, style, transform, and tags; that is, after the function returns, the target shape and the source shape share the same ink, style, and transform objects. This function increments by 1 the owner counts of the source shape's ink, style, and transform, and disposes of the ink, style, and transform of the target shape.

If you specify nil for the target parameter, this function creates a new shape to copy the contents of the source shape into.

The GXCopyDeepToShape function is similar to the GXCopyToShape function except that it performs these additional operations:

• For bitmap shapes, GXCopyDeepToShape also copies the complete pixel image.
• For picture shapes, GXCopyDeepToShape also copies each shape in the source picture. If the source picture contains other picture shapes, their shapes are also recursively copied. The styles, inks, and transforms of the shapes within the picture are not copied; instead the copied shapes share references to the styles, inks, and transforms of the original shapes, and the GXCopyDeepToShape function increments by 1 the owner counts of the original styles, inks, and transforms.
• For glyph and layout shapes, GXCopyDeepToShape also copies the set of style objects referenced in the style list that is part of the shape's geometry.

Because the GXCopyDeepToShape function copies the pixel image of bitmap shapes and the shapes contained within picture shapes, you can use it to create a copy of a bitmap or a picture, and then modify the copy without changing the original bitmap or picture.

SPECIAL CONSIDERATIONS

If you specify nil for the target parameter and no error occurs, the GXCopyDeepToShape function creates a new shape object; you are responsible for disposing of that object when you no longer need it.

If you try to copy a picture into a shape that is contained in the picture, the GXCopyDeepToShape function posts a picture_cannot_contain_itself error. If the target shape is locked, this function posts a shape_access_not_allowed error.
If you try to copy a shape of one type into the default shape of another type, this function posts a cannot_dispose_default_shape warning.

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
shape_is_nil
shape_access_not_allowed	(debugging version)
picture_cannot_contain_itself	(debugging version)
Warnings
cannot_dispose_default_shape	(debugging version)

SEE ALSO

To create a new shape that is a copy of the default shape instead of a copy of an existing shape, use the GXNewShape function, described on page 2-54.

To make a copy of an existing shape without copying all information for bitmap shapes, picture shapes, glyph shape, and layout shapes, use the GXCopyToShape function, described in the previous section.

For information about copying typographic shapes, see the typographic shapes chapter of Inside Macintosh: QuickDraw GX Typography.